CAdoRecord Class

Represents a row from a Recordset or the data provider, or an object returned by a semi-structured data provider, such as a file or directory.

Include file: CADORecord.inc (include CADODB.inc)

Methods and Properties

Name	Description
ActiveConnection	Indicates to which `Connection` object the specified `Record` object currently belongs.
Attach	Attaches a reference to an ADO `Record` object to the class.
Cancel	Cancels execution of a pending, asynchronous method call.
Close	Closes a `Record` object and any dependent objects.
CopyRecord	Copies an entity represented by a Record to another location.
DeleteRecord	Deletes the entity represented by a `Record`.
Fields	Gets a reference to the Fields collection of a `Record` object.
GetChildren	Returns a `Recordset` whose rows represent the children of a collection `Record`.
GetErrorInfo	Returns information about ADO errors.
Mode	Sets or returns a ConnectModeEnum value.
MoveRecord	Moves an entity represented by a `Record` to another location.
Open	Opens an existing `Record` object, or creates a new item represented by the `Record` (such as a file or directory).
ParentURL	Indicates an absolute URL string that points to the parent `Record` of the current `Record` object.
Properties	Returns a reference to the Properties collection.
RecordType	Indicates the type of `Record` object.
Source	Indicates the data source or object represented by the `Record`.
State	Indicates for all applicable objects whether the state of the object is open or closed.

Remarks

A Record object represents one row of data, and has some conceptual similarities with a one-row Recordset. Depending upon the capabilities of your provider, Record objects may be returned directly from your provider instead of a one-row Recordset, for example when an SQL query that selects only one row is executed. Or, a Record object can be obtained directly from a Recordset object. Or, a Record can be returned directly from a provider to semi-structured data, such as the Microsoft Exchange OLE DB provider.

You can view the fields associated with the Record object by way of the Fields collection on the Record object. ADO allows object-valued columns including Recordset, SafeArray, and scalar values in the Fields collection of Record objects.

If the Record object represents a row in a Recordset, then it is possible to return to that original Recordset with the Source property.

The Record object can also be used by semi-structured data providers such as the Microsoft OLE DB Provider for Internet Publishing, to model tree-structured namespaces. Each node in the tree is a Record object with associated columns. The columns can represent the attributes of that node and other relevant information. The Record object can represent both a leaf node and a non-leaf node in the tree structure. Non-leaf nodes have other nodes as their contents while leaf nodes do not have such contents. Leaf nodes typically contain binary streams of data while non-leaf nodes may also have a default binary stream associated with them. Properties on the Record object identify the type of node.

The Record object also represents an alternative way for navigating hierarchically organized data. A Record object may be created to represent the root of a specific sub-tree in a large tree structure and new Record objects may be opened to represent child nodes.

A resource (for example, a file or directory) can be uniquely identified by an absolute URL. A Connection object is implicitly created and set to the Record object when the Record is opened with an absolute URL. A Connection object may explicitly be set to the Record object via the ActiveConnection property. The files and directories accessible via the Connection object define the context in which Record operations may occur.

Data modification and navigation methods on the Record object also accept a relative URL, which locates a resource using an absolute URL or the Connection object context as a starting point.

Note: URLs using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

A Connection object is associated with each Record object. Therefore, Record object operations can be part of a transaction by invoking Connection object transaction methods.

The Record object does not support ADO events, and therefore will not respond to notifications.

With the methods and properties of a Record object, you can do the following:

Set or return the associated Connection object with the ActiveConnection property.
Indicate access permissions with the Mode property.
Return the URL of the directory, if any, that contains the resource represented by the Record with the ParentURL property.
Indicate the absolute URL, relative URL, or Recordset from which the Record is derived with the Source property.
Indicate the current status of the Record with the State property.
Indicate the type of Record—simple, collection, or structured document—with the RecordType property.
Halt execution of an asynchronous operation with the Cancel method.
Disassociate the Record from a data source with the Close method.
Copy the file or directory represented by a Record to another location with the CopyRecord method.
Delete the file, or directory and subdirectories, represented by a Record with the DeleteRecord method.
Open a Recordset containing rows that represent the subdirectories and files of the entity represented by the Record with the GetChildren method.
Move (rename) the file, or directory and subdirectories, represented by a Record to another location with the MoveRecord method.
Associate the Record with an existing data source, or create a new file or directory with the Open method.

Fields

A Record object has two special fields that can be indexed with FieldEnum constants. One constant accesses a field containing the default stream for the Record, and the other accesses a field containing the absolute URL string for the Record.

Certain providers (for example, the Microsoft OLE DB Provider for Internet Publishing) may populate the Fields collection with a subset of available fields for the Record or Recordset. Other fields will not be added to the collection until they are first referenced by name or indexed by your code.

Each Field object corresponds to a column in the Recordset. You use the Value property of Field objects to set or return data for the current record. Depending on the functionality the provider exposes, some collections, methods, or properties of a Field object may not be available.

With the collections, methods, and properties of a Field object, you can do the following:

Return the name of a field with the Name property.
View or change the data in the field with the Value property. Value is the default property of the Field object.
Return the basic characteristics of a field with the Type_, Precision, and NumericScale properties.
Return the declared size of a field with the DefinedSize property.
Return the actual size of the data in a given field with the ActualSize property.
Determine what types of functionality are supported for a given field with the Attributes property and Properties collection.
Manipulate the values of fields containing long binary or long character data with the AppendChunk and GetChunk methods.
If the provider supports batch updates, resolve discrepancies in field values during batch updating with the OriginalValue and UnderlyingValue properties.

All of the metadata properties (Name, Type_, DefinedSize, Precision, and NumericScale) are available before opening the Field object’s Recordset. Setting them at that time is useful for dynamically constructing forms.

ActiveConnection

Sets or returns a string value that contains a definition for a connection if the connection is closed, or a Variant containing the current Connection object if the connection is open. Default is a null object reference.

PROPERTY ActiveConnection (BYREF vConn AS DVARIANT)
PROPERTY ActiveConnection (BYVAL pconn AS Afx_ADOConnection PTR)
PROPERTY ActiveConnection (BYREF pconn AS CAdoConnection)
PROPERTY ActiveConnection () AS Afx_ADOConnection

Parameter	Description
vConn	A string value that contains a definition for a connection if the connection is closed, or a Variant containing the current `Connection` object if the connection is open.
pconn	A reference to the `Connection` object or to the ’CAdoConnection` class.

Return value

A reference to the Afx_ADOConnection object. You must release it calling the Release method when no longer needed.

Remarks

This property is read/write when the Record object is closed, and may contain a connection string or reference to an open Connection object. This property is read-only when the Record object is open, and contains a reference to an open Connection object.

A Connection object is created implicitly when the Record object is opened from a URL. Open the Record with an existing, open Connection object by assigning the Connection object to this property, or using the Connection object as a parameter in the Open method call. If the Record is opened from an existing Record or Recordset, then it is automatically associated with that Record or Recordset object’s Connection object.

Note: URLs using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

Attach

Attaches a record to the class.

FUNCTION Attach (BYVAL pRecordset AS Afx_ADORecord PTR, BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
pRecordset	A reference to an Afx_ADORecord object.
fAddRef	TRUE = increase the reference count; FALSE = don’t increase the reference count.

Cancel

Cancels execution of a pending, asynchronous method call.

FUNCTION Cancel () AS HRESULT

Return value

S_OK (0) or an HRESULT code.

Remarks

Use the Cancel method to terminate execution of an asynchronous method call (that is, a method invoked with the adAsyncConnect, adAsyncExecute, or adAsyncFetch option).

For a Record object, the last asynchronous call to the CopyRecord, DeleteRecord, MoveRecord or Open methods is terminated.

Close

Closes a Record object and any dependent objects.

FUNCTION Close () AS HRESULT

Return value

S_OK (0) or an HRESULT code.

Remarks

Use the Close method to close a Record to free any associated system resources. Closing an object does not remove it from memory; you can change its property settings and open it again later. To completely eliminate an object from memory, release the connection calling the Release method of the interface.

CopyRecord

Copies a entity represented by a Record to another location.

FUNCTION CopyRecord (BYREF wszSource AS WSTRING = "", BYREF wszDestination AS WSTRING = "", _
   BYREF wszUserName AS WSTRING = "", BYREF wszPassword AS WSTRING = "", _
   BYVAL Options AS MoveRecordOptionsEnum = adCopyUnspecified, _
   BYVAL Async AS BOOLEAN = FALSE) AS DWSTRING

Parameter	Description
wszSource	Optional. A string value that contains a URL specifying the entity to be copied (for example, a file or directory). If Source is omitted or specifies an empty string, the file or directory represented by the current `Record` will be copied.
wszDestination	Optional. A string value that contains a URL specifying the location where Source will be copied.
wszUserName	Optional. A string value that contains the user ID that, if needed, authorizes access to Destination.
wszPassword	Optional. A string value that contains the password that, if needed, verifies UserName.
Options	Optional. A CopyRecordOptionsEnum value that has a default value of adCopyUnspecified. Specifies the behavior of this method.
Async	Optional. A Boolean value that, when True, specifies that this operation should be asynchronous.

CopyRecordOptionsEnum

Specifies the behavior of the CopyRecord method.

Constant	Description
adCopyAllowEmulation	Indicates that the Source provider attempts to simulate the copy using download and upload operations if this method fails due to Destination being on a different server or is serviced by a different provider than Source. Note that differing provider capabilities may hamper performance or lose data.
adCopyNonRecursive	Copies the current directory, but none of its subdirectories, to the destination. The copy operation is not recursive.
adCopyOverWrite	Overwrites the file or directory if the Destination points to an existing file or directory.
adCopyUnspecified	Default. Performs the default copy operation: The operation fails if the destination file or directory already exists, and the operation copies recursively.

Return value

Typically returns the value of Destination. However, the exact value returned is provider-dependent.

Remarks

The values of Source and Destination must not be identical; otherwise, a run-time error occurs. At least one of the server, path, or resource names must differ.

All children (for example, subdirectories) of Source are copied recursively, unless adCopyNonRecursive is specified. In a recursive operation, Destination must not be a subdirectory of Source; otherwise, the operation will not complete.

This method fails if Destination identifies an existing entity (for example, a file or directory), unless adCopyOverWrite is specified.

Important: Use the adCopyOverWrite option judiciously. For example, specifying this option when copying a file to a directory will delete the directory and replace it with the file.

Note: URLs using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

DeleteRecord

Deletes the entity represented by a Record.

FUNCTION DeleteRecord (BYREF wszSource WSTRING = "", BYVAL Async BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszSource	Optional. A string value that contains a URL identifying the entity (for example, the file or directory) to be deleted. If Source is omitted or specifies an empty string, the entity represented by the current `Record` is deleted. If the `Record` is a collection record (RecordType of adCollectionRecord, such as a directory) all children (for example, subdirectories) will also be deleted.
Async	Optional. A Boolean value that, when True, specifies that the delete operation is asynchronous.

Return value

S_OK (0) or an HRESULT code.

Remarks

Operations on the object represented by this Record may fail after this method completes. After calling DeleteRecord, the Record should be closed because the behavior of the Record may become unpredictable depending upon when the provider updates the Record with the data source.

If this Record was obtained from a Recordset, then the results of this operation will not be reflected immediately in the Recordset. Refresh the Recordset by closing and re-opening it, or by executing the Recordset Requery, or Update and Resync methods.

Note: URLs using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

Fields

Gets a reference to the Fields collection of a Record object.

PROPERTY Fields () AS Afx_ADOFields PTR

GetChildren

Returns a Recordset whose rows represent the children of a collection Record.

FUNCTION GetChildren () AS Afx_ADORecordset

Return value

A Recordset object reference.

Remarks

The provider determines what columns exist in the returned Recordset. For example, a document source provider always returns a resource Recordset.

GetErrorInfo

Returns information about ADO errors.

FUNCTION GetErrorInfo (BYVAL nError AS HRESULT = 0) AS DWSTRING

Parameter	Description
nError	Optional. The error code.

Return value

A description of the error(s).

Mode

Sets or returns a ConnectModeEnum value. The default value for a Record object is adModeRead.

PROPERTY Mode () AS ConnectModeEnum
PROPERTY Mode (BYVAL Mode AS ConnectModeEnum)

Parameter	Description
Mode	A ConnectModeEnum value.

Return value

A ConnectModeEnum value.

ConnectModeEnum

Specifies the available permissions for modifying data in a Connection, opening a Record, or specifying values for the Mode property of the Record and Stream objects.

Constant	Description
adModeRead	Indicates read-only permissions.
adModeReadWrite	Indicates read/write permissions.
adModeRecursive	Used in conjunction with the other ShareDeny values (adModeShareDenyNone, adModeShareDenyWrite, or adModeShareDenyRead) to propagate sharing restrictions to all sub-records of the current `Record`. It has no affect if the `Record` does not have any children. A run-time error is generated if it is used with adModeShareDenyNone only. However, it can be used with adModeShareDenyNone when combined with other values. For example, you can use “adModeRead OR adModeShareDenyNone OR adModeRecursive”.
adModeShareDenyNone	Allows others to open a connection with any permissions. Neither read nor write access can be denied to others.
adModeShareDenyRead	Prevents others from opening a connection with read permissions.
adModeShareDenyWrite	Prevents others from opening a connection with write permissions.
adModeShareExclusive	Prevents others from opening a connection.
adModeUnknown	Default. Indicates that the permissions have not yet been set or cannot be determined.
adModeWrite	Indicates write-only permissions.

MoveRecord

Moves a entity represented by a Record to another location.

FUNCTION MoveRecord (BYREF wszSource AS WSTRING = "", BYREF wszDestination AS WSTRING = "", _
   BYREF wszUserName AS WSTRING = "", BYREF wszPassword AS WSTRING = "", _
   BYVAL Options AS MoveRecordOptionsEnum = adMoveUnspecified, _
   BYVAL Async AS BOOLEAN = FALSE) AS DWSTRING

Parameter	Description
wszSource	Optional. A string value that contains a URL identifying the `Record` to be moved. If Source is omitted or specifies an empty string, the object represented by this `Record` is moved. For example, if the `Record` represents a file, the contents of the file are moved to the location specified by Destination.
wszDestination	Optional. A string value that contains a URL specifying the location where Source will be moved.
wszUserName	Optional. A string value that contains the user ID that, if needed, authorizes access to Destination.
wszPassword	Optional. A string value that contains the password that, if needed, verifies UserName.
Options	Optional. A MoveRecordOptionsEnum value whose default value is adMoveUnspecified. Specifies the behavior of this method.
Async	Optional. A Boolean value that, when True, specifies that this operation should be asynchronous.

MoveRecordOptionsEnum

Specifies the behavior of the Record object MoveRecord method.

Parameter	Description
adMoveUnspecified	Default. Performs the default move operation: The operation fails if the destination file or directory already exists, and the operation updates hypertext links.
adMoveOverWrite	Overwrites the destination file or directory, even if it already exists.
adMoveDontUpdateLinks	Modifies the default behavior of MoveRecord method by not updating the hypertext links of the source Record. The default behavior depends on the capabilities of the provider. Move operation updates links if the provider is capable. If the provider cannot fix links or if this value is not specified, then the move succeeds even when links have not been fixed.
adMoveAllowEmulation	Requests that the provider attempt to simulate the move (using download, upload, and delete operations). If the attempt to move the Record fails because the destination URL is on a different server or serviced by a different provider than the source, this may cause increased latency or data loss, due to different provider capabilities when moving resources between providers.

Remarks

The values of Source and Destination must not be identical; otherwise, a run-time error occurs. At least one of the server, path, or resource names must differ.

For files moved using the Internet Publishing Provider, this method updates all hypertext links in files being moved unless otherwise specified by Options. This method fails if Destination identifies an existing object (for example, a file or directory), unless adMoveOverWrite is specified.

Note: Use the adMoveOverWrite option judiciously. For example, specifying this option when moving a file to a directory will delete the directory and replace it with the file.

Certain attributes of the Record object, such as the ParentURL property, will not be updated after this operation completes. Refresh the Record object’s properties by closing the Record, then re-opening it with the URL of the location where the file or directory was moved.

If this Record was obtained from a Recordset, the new location of the moved file or directory will not be reflected immediately in the Recordset. Refresh the Recordset by closing and re-opening it.

Note: URLs using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

Open

Opens an existing Record object, or creates a new item represented by the Record (such as a file or directory).

FUNCTION Open (BYREF dvSource AS DVARIANT = TYPE<VARIANT>(VT_ERROR,0,0,0,DISP_E_PARAMNOTFOUND), _
   BYREF dvActiveConnection AS DVARIANT = TYPE<VARIANT>(VT_ERROR,0,0,0,DISP_E_PARAMNOTFOUND), _
   BYVAL nMode AS ConnectModeEnum = adModeUnknown, _
   BYVAL CreateOptions AS RecordCreateOptionsEnum = adFailIfNotExists, _
   BYVAL Options AS RecordOpenOptionsEnum = adOpenRecordUnspecified, _
   BYREF wszUserName AS WSTRING = "", BYREF wszPassword AS WSTRING = "") AS HRESULT

Parameter	Description
dvSource	Optional. A Variant that may represent the URL of the entity to be represented by this `Record` object, a Command, an open `Recordset` or another `Record` object, a string containing a SQL SELECT statement or a table name.
dvActiveConnection	Optional. A Variant that represents the connect string or open `Connection` object.
nMode	Optional. A ConnectModeEnum value, whose default value is adModeUnknown, that specifies the access mode for the resultant `Record` object.
CreateOptions	Optional. A RecordCreateOptionsEnum value, whose default value is adFailIfNotExists, that specifies whether an existing file or directory should be opened, or a new file or directory should be created. If set to the default value, the access mode is obtained from the Mode property. This parameter is ignored when the cbsSource parameter doesn’t contain a URL.
Options	Optional. Optional. A RecordOpenOptionsEnum value, whose default value is adOpenRecordUnspecified, that specifies options for opening the `Record`. These values may be combined.
wszUserName	Optional. A string value that contains the user ID that, if needed, authorizes access to cbsSource.
wszPassword	Optional. A string value that contains the password that, if needed, verifies cbsUserName.

Return value

S_OK (0) or an HRESULT value.

Remarks

Source may be:

A URL. If the protocol for the URL is http, then the Internet Provider will be invoked by default. If the URL points to a node that contains an executable script (such as an .ASP page), then a Record containing the source rather than the executed contents is opened by default. Use the Options argument to modify this behavior.
A Record object. A Record object opened from another Record will clone the original Record object.
A Command object. The opened Record object represents the single row returned by executing the Command. If the results contain more than a single row, the contents of the first row are placed in the record and an error may be added to the Errors collection.
A SQL SELECT statement. The opened Record object represents the single row returned by executing the contents of the string. If the results contain more than a single row, the contents of the first row are placed in the record and an error may be added to the Errors collection.
A table name.
If the Record object represents an entity that cannot be accessed with a URL (for example, a row of a Recordset derived from a database), then the values of both the ParentURL property and the field accessed with the adRecordURL constant are null.

Note: URLs using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

ParentURL

Indicates an absolute URL string that points to the parent Record of the current Record object.

PROPERTY ParentURL () AS DWSTRING

Return value

The absolute URL string that points to the parent Record of the current Record object.

Remarks

The ParentURL property depends upon the source used to open the Record object. For example, the Record may be opened with a source containing a relative path name of a directory referenced by the ActiveConnection property.

Suppose “second” is a folder contained under “first”. Open the Record object with the following:

AdoRecord.Open "second", "http://first, Mode, CreateOptions, Options, UserName, Password

Now, the value of the ParentURL property is “http://first”, the same as ActiveConnection.

The source may also be an absolute URL such as, “http://first/second”. The ParentURL property is then “http://first”, the level above “second”.

This property may be a null value if:

There is no parent for the current object; for example, if the Record object represents the root of a directory.
The Record object represents an entity that cannot be specified with a URL.

This property is read-only.

Note: This property is only supported by document source providers, such as the Microsoft OLE DB Provider for Internet Publishing.

Note: URLs using the http scheme will automatically invoke the Microsoft OLE DB Provider for Internet Publishing.

Note: If the current record contains a data record from an ADO Recordset, accessing the ParentURL property causes a run-time error, indicating that no URL is possible.

Properties

Returns a reference to the Properties collection.

PROPERTY Properties () AS Afx_ADOProperties

Return value

A Properties object reference.

RecordType

Indicates the type of Record object.

PROPERTY RecordType () AS RecordTypeEnum

Return value

A RecordTypeEnum value.

RecordTypeEnum

Specifies the type of Record object.

Constant	Description
adSimpleRecord	Indicates a simple record (does not contain child nodes).
adCollectionRecord	Indicates a collection record (contains child nodes).
adRecordUnknown	Indicates that the type of this `Record` is unknown.
adStructDoc	Indicates a special kind of collection record that represents COM structured documents.

Source

Indicates the data source or object represented by the Record.

PROPERTY Source () AS DVARIANT
PROPERTY Source (BYREF wszSource AS WSTRING)
PROPERTY PutRefSource (BYVAL pSource AS IDispatch PTR)

Parameter	Description
wszSource	An absolute or relative URL string.
pSource	A `Recordset` or Command object.

Note: I have used PutRefSource, instead of Source, for the overloaded property because, otherwise, the compiler fails with an ambiguous call error.

Return value

The absolute or relative URL string or a reference to an already open Record.

Remarks

The Source property returns the Source argument of the Record object Open method. It can contain an absolute or relative URL string. An absolute URL can be used without setting the ActiveConnection property to directly open the Record object. An implicit Connection object is created in this case.

The Source property can also contain a reference to an already open Recordset, which opens a Record object representing the current row in the Recordset.

State

Indicates for all applicable objects whether the state of the object is open or closed.

PROPERTY State () AS LONG

Return value

The current record state.

ObjectStateEnum

Specifies whether the Open method of a Connection object should return after (synchronously) or before (asynchronously) the connection is established.

Constant	Description
adStateClosed	Indicates that the object is closed.
adStateOpen	Indicates that the object is open.
adStateConnecting	Indicates that the object is connecting.
adStateExecuting	Indicates that the object is executing a command.
adStateFetching	Indicates that the rows of the object are being retrieved.

Remarks

You can use the State property to determine the current state of a given object at any time.

The object’s State property can have a combination of values. For example, if a statement is executing, this property will have a combined value of adStateOpen and adStateExecuting.